IRIX Base Documentation 2001 May

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / u_man / cat3 / Tk / parseargv.z / parseargv

Wrap

Text File | 1998-10-30 | 24.7 KB | 463 lines

TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) NNNNAAAAMMMMEEEE Tk_ParseArgv - process command-line options SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>> int TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv(_i_n_t_e_r_p, _t_k_w_i_n, _a_r_g_c_P_t_r, _a_r_g_v, _a_r_g_T_a_b_l_e, _f_l_a_g_s) AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS Tcl_Interp *_i_n_t_e_r_p (in) Interpreter to use for returning error messages. Tk_Window _t_k_w_i_n (in) Window to use when arguments specify Tk options. If NULL, then no Tk options will be processed. int _a_r_g_c_P_t_r (in/out) Pointer to number of arguments in argv; gets modified to hold number of unprocessed arguments that remain after the call. char **_a_r_g_v (in/out) Command line arguments passed to main program. Modified to hold unprocessed arguments that remain after the call. Tk_ArgvInfo *_a_r_g_T_a_b_l_e (in) Array of argument descriptors, terminated by element with type TK_ARGV_END. int _f_l_a_g_s (in) If non-zero, then it specifies one or more flags that control the parsing of arguments. Different flags may be OR'ed together. The flags currently defined are TK_ARGV_DONT_SKIP_FIRST_ARG, TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv processes an array of command-line arguments according to a table describing the kinds of arguments that are expected. Each of the arguments in _a_r_g_v is processed in turn: if it matches one of the entries in _a_r_g_T_a_b_l_e, the argument is processed according to that entry and discarded. The arguments that do not match anything in _a_r_g_T_a_b_l_e are copied down to the beginning of _a_r_g_v (retaining their original order) and returned to the caller. At the end of the call TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv sets *_a_r_g_c_P_t_r to hold the number of arguments that are left in _a_r_g_v, and _a_r_g_v[*_a_r_g_c_P_t_r] will hold the value NULL. Normally, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv assumes that _a_r_g_v[_0] is a command name, so it is treated like an argument that PPPPaaaaggggeeee 1111 TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) doesn't match _a_r_g_T_a_b_l_e and returned to the caller; however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in _f_l_a_g_s then _a_r_g_v[_0] will be processed just like the other elements of _a_r_g_v. TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv normally returns the value TCL_OK. If an error occurs while parsing the arguments, then TCL_ERROR is returned and TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will leave an error message in _i_n_t_e_r_p->_r_e_s_u_l_t in the standard Tcl fashion. In the event of an error return, *_a_r_g_v_P_t_r will not have been modified, but _a_r_g_v could have been partially modified. The possible causes of errors are explained below. The _a_r_g_T_a_b_l_e array specifies the kinds of arguments that are expected; each of its entries has the following structure: ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt { cccchhhhaaaarrrr*_k_e_y; iiiinnnntttt _t_y_p_e; cccchhhhaaaarrrr*_s_r_c; cccchhhhaaaarrrr*_d_s_t; cccchhhhaaaarrrr*_h_e_l_p; }}}} TTTTkkkk____AAAArrrrggggvvvvIIIInnnnffffoooo;;;; The _k_e_y field is a string such as ``-display'' or ``-bg'' that is compared with the values in _a_r_g_v. _T_y_p_e indicates how to process an argument that matches _k_e_y (more on this below). _S_r_c and _d_s_t are additional values used in processing the argument. Their exact usage depends on _t_y_p_e, but typically _s_r_c indicates a value and _d_s_t indicates where to store the value. The cccchhhhaaaarrrr **** declarations for _s_r_c and _d_s_t are placeholders: the actual types may be different. Lastly, _h_e_l_p is a string giving a brief description of this option; this string is printed when users ask for help about command-line options. When processing an argument in _a_r_g_v, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv compares the argument to each of the _k_e_y's in _a_r_g_T_a_b_l_e. TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv selects the first specifier whose _k_e_y matches the argument exactly, if such a specifier exists. Otherwise TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv selects a specifier for which the argument is a unique abbreviation. If the argument is a unique abbreviation for more than one specifier, then an error is returned. If there is no matching entry in _a_r_g_T_a_b_l_e, then the argument is skipped and returned to the caller. Once a matching argument specifier is found, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv processes the argument according to the _t_y_p_e field of the specifier. The argument that matched _k_e_y is called ``the matching argument'' in the descriptions below. As part of the processing, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv may also use the next argument in _a_r_g_v after the matching argument, which is called ``the following argument''. The legal values for _t_y_p_e, and the processing that they cause, are as follows: PPPPaaaaggggeeee 2222 TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTKKKK____AAAARRRRGGGGVVVV____EEEENNNNDDDD Marks the end of the table. The last entry in _a_r_g_T_a_b_l_e must have this type; all of its other fields are ignored and it will never match any arguments. TTTTKKKK____AAAARRRRGGGGVVVV____CCCCOOOONNNNSSSSTTTTAAAANNNNTTTT _S_r_c is treated as an integer and _d_s_t is treated as a pointer to an integer. _S_r_c is stored at *_d_s_t. The matching argument is discarded. TTTTKKKK____AAAARRRRGGGGVVVV____IIIINNNNTTTT The following argument must contain an integer string in the format accepted by ssssttttrrrrttttoooollll (e.g. ``0'' and ``0x'' prefixes may be used to specify octal or hexadecimal numbers, respectively). _D_s_t is treated as a pointer to an integer; the following argument is converted to an integer value and stored at *_d_s_t. _S_r_c is ignored. The matching and following arguments are discarded from _a_r_g_v. TTTTKKKK____AAAARRRRGGGGVVVV____FFFFLLLLOOOOAAAATTTT The following argument must contain a floating-point number in the format accepted by ssssttttrrrrttttoooollll. _D_s_t is treated as the address of an double-precision floating point value; the following argument is converted to a double-precision value and stored at *_d_s_t. The matching and following arguments are discarded from _a_r_g_v. TTTTKKKK____AAAARRRRGGGGVVVV____SSSSTTTTRRRRIIIINNNNGGGG In this form, _d_s_t is treated as a pointer to a (char *); TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv stores at *_d_s_t a pointer to the following argument, and discards the matching and following arguments from _a_r_g_v. _S_r_c is ignored. TTTTKKKK____AAAARRRRGGGGVVVV____UUUUIIIIDDDD This form is similar to TK_ARGV_STRING, except that the argument is turned into a Tk_Uid by calling TTTTkkkk____GGGGeeeettttUUUUiiiidddd. _D_s_t is treated as a pointer to a Tk_Uid; TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv stores at *_d_s_t the Tk_Uid corresponding to the following argument, and discards the matching and following arguments from _a_r_g_v. _S_r_c is ignored. TTTTKKKK____AAAARRRRGGGGVVVV____CCCCOOOONNNNSSSSTTTT____OOOOPPPPTTTTIIIIOOOONNNN This form causes a Tk option to be set (as if the ooooppppttttiiiioooonnnn command had been invoked). The _s_r_c field is treated as a pointer to a string giving the value of an option, and _d_s_t is treated as a pointer to the name of the option. The matching argument is discarded. If _t_k_w_i_n is NULL, then argument specifiers of this type are ignored (as if they did not exist). TTTTKKKK____AAAARRRRGGGGVVVV____OOOOPPPPTTTTIIIIOOOONNNN____VVVVAAAALLLLUUUUEEEE This form is similar to TK_ARGV_CONST_OPTION, except that the value of the option is taken from the following argument instead of from _s_r_c. _D_s_t is used as the name of the option. _S_r_c is ignored. The matching and following arguments are discarded. If _t_k_w_i_n is NULL, then argument specifiers of this type are ignored (as if they did PPPPaaaaggggeeee 3333 TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) not exist). TTTTKKKK____AAAARRRRGGGGVVVV____OOOOPPPPTTTTIIIIOOOONNNN____NNNNAAAAMMMMEEEE____VVVVAAAALLLLUUUUEEEE In this case the following argument is taken as the name of a Tk option and the argument after that is taken as the value for that option. Both _s_r_c and _d_s_t are ignored. All three arguments are discarded from _a_r_g_v. If _t_k_w_i_n is NULL, then argument specifiers of this type are ignored (as if they did not exist). TTTTKKKK____AAAARRRRGGGGVVVV____HHHHEEEELLLLPPPP When this kind of option is encountered, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv uses the _h_e_l_p fields of _a_r_g_T_a_b_l_e to format a message describing all the valid arguments. The message is placed in _i_n_t_e_r_p->_r_e_s_u_l_t and TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv returns TCL_ERROR. When this happens, the caller normally prints the help message and aborts. If the _k_e_y field of a TK_ARGV_HELP specifier is NULL, then the specifier will never match any arguments; in this case the specifier simply provides extra documentation, which will be included when some other TK_ARGV_HELP entry causes help information to be returned. TTTTKKKK____AAAARRRRGGGGVVVV____RRRREEEESSSSTTTT This option is used by programs or commands that allow the last several of their options to be the name and/or options for some other program. If a TTTTKKKK____AAAARRRRGGGGVVVV____RRRREEEESSSSTTTT argument is found, then TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv doesn't process any of the remaining arguments; it returns them all at the beginning of _a_r_g_v (along with any other unprocessed arguments). In addition, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv treats _d_s_t as the address of an integer value, and stores at *_d_s_t the index of the first of the TTTTKKKK____AAAARRRRGGGGVVVV____RRRREEEESSSSTTTT options in the returned _a_r_g_v. This allows the program to distinguish the TTTTKKKK____AAAARRRRGGGGVVVV____RRRREEEESSSSTTTT options from other unprocessed options that preceded the TTTTKKKK____AAAARRRRGGGGVVVV____RRRREEEESSSSTTTT. TTTTKKKK____AAAARRRRGGGGVVVV____FFFFUUUUNNNNCCCC For this kind of argument, _s_r_c is treated as the address of a procedure, which is invoked to process the following argument. The procedure should have the following structure: iiiinnnntttt _f_u_n_c(_d_s_t, _k_e_y, _n_e_x_t_A_r_g) cccchhhhaaaarrrr *_d_s_t; cccchhhhaaaarrrr *_k_e_y; cccchhhhaaaarrrr *_n_e_x_t_A_r_g; { } The _d_s_t and _k_e_y parameters will contain the corresponding fields from the _a_r_g_T_a_b_l_e entry, and _n_e_x_t_A_r_g will point to the following argument from _a_r_g_v (or NULL if there aren't any more arguments left in _a_r_g_v). If _f_u_n_c uses _n_e_x_t_A_r_g (so that TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv should discard it), then it should return 1. Otherwise it should return 0 and TTTTkkkkPPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will process the following argument in the normal PPPPaaaaggggeeee 4444 TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) fashion. In either event the matching argument is discarded. TTTTKKKK____AAAARRRRGGGGVVVV____GGGGEEEENNNNFFFFUUUUNNNNCCCC This form provides a more general procedural escape. It treats _s_r_c as the address of a procedure, and passes that procedure all of the remaining arguments. The procedure should have the following form: iiiinnnntttt _g_e_n_f_u_n_c(_d_s_t, _i_n_t_e_r_p, _k_e_y, _a_r_g_c, _a_r_g_v) cccchhhhaaaarrrr *_d_s_t; TTTTccccllll____IIIInnnntttteeeerrrrpppp *_i_n_t_e_r_p; cccchhhhaaaarrrr *_k_e_y; iiiinnnntttt _a_r_g_c; cccchhhhaaaarrrr **_a_r_g_v; { } The _d_s_t and _k_e_y parameters will contain the corresponding fields from the _a_r_g_T_a_b_l_e entry. _I_n_t_e_r_p will be the same as the _i_n_t_e_r_p argument to TTTTccccllll____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv. _A_r_g_c and _a_r_g_v refer to all of the options after the matching one. _G_e_n_f_u_n_c should behave in a fashion similar to TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv: parse as many of the remaining arguments as it can, then return any that are left by compacting them to the beginning of _a_r_g_v (starting at _a_r_g_v[0]). _G_e_n_f_u_n_c should return a count of how many arguments are left in _a_r_g_v; TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will process them. If _g_e_n_f_u_n_c encounters an error then it should leave an error message in _i_n_t_e_r_p->_r_e_s_u_l_t, in the usual Tcl fashion, and return -1; when this happens TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will abort its processing and return TCL_ERROR. FFFFLLLLAAAAGGGGSSSS TTTTKKKK____AAAARRRRGGGGVVVV____DDDDOOOONNNNTTTT____SSSSKKKKIIIIPPPP____FFFFIIIIRRRRSSSSTTTT____AAAARRRRGGGG TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv normally treats _a_r_g_v[_0] as a program or command name, and returns it to the caller just as if it hadn't matched _a_r_g_T_a_b_l_e. If this flag is given, then _a_r_g_v[_0] is not given special treatment. TTTTKKKK____AAAARRRRGGGGVVVV____NNNNOOOO____AAAABBBBBBBBRRRREEEEVVVV Normally, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv accepts unique abbreviations for _k_e_y values in _a_r_g_T_a_b_l_e. If this flag is given then only exact matches will be acceptable. TTTTKKKK____AAAARRRRGGGGVVVV____NNNNOOOO____LLLLEEEEFFFFTTTTOOOOVVVVEEEERRRRSSSS Normally, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv returns unrecognized arguments to the caller. If this bit is set in _f_l_a_g_s then TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will return an error if it encounters any argument that doesn't match _a_r_g_T_a_b_l_e. The only exception to this rule is _a_r_g_v[_0], which will be returned to the caller with no errors as long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified. PPPPaaaaggggeeee 5555 TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTKKKK____AAAARRRRGGGGVVVV____NNNNOOOO____DDDDEEEEFFFFAAAAUUUULLLLTTTTSSSS Normally, TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv searches an internal table of standard argument specifiers in addition to _a_r_g_T_a_b_l_e. If this bit is set in _f_l_a_g_s, then TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv will use only _a_r_g_T_a_b_l_e and not its default table. EEEEXXXXAAAAMMMMPPPPLLLLEEEE Here is an example definition of an _a_r_g_T_a_b_l_e and some sample command lines that use the options. Note the effect on _a_r_g_c and _a_r_g_v; arguments processed by TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv are eliminated from _a_r_g_v, and _a_r_g_c is updated to reflect reduced number of arguments. /* * Define and set default values for globals. */ int debugFlag = 0; int numReps = 100; char defaultFileName[] = "out"; char *fileName = defaultFileName; Boolean exec = FALSE; /* * Define option descriptions. */ Tk_ArgvInfo argTable[] = { {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag, "Turn on debugging printfs"}, {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps, "Number of repetitions"}, {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName, "Name of file for output"}, {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec, "File to exec, followed by any arguments (must be last argument)."}, {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL, (char *) NULL} }; main(argc, argv) int argc; char *argv[]; { ... if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { fprintf(stderr, "%s\n", interp->result); exit(1); } /* * Remainder of the program. */ PPPPaaaaggggeeee 6666 TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv((((3333TTTTkkkk)))) } Note that default values can be assigned to variables named in _a_r_g_T_a_b_l_e: the variables will only be overwritten if the particular arguments are present in _a_r_g_v. Here are some example command lines and their effects. prog -N 200 infile # just sets the numReps variable to 200 prog -of out200 infile # sets fileName to reference "out200" prog -XN 10 infile # sets the debug flag, also sets numReps In all of the above examples, _a_r_g_c will be set by TTTTkkkk____PPPPaaaarrrrsssseeeeAAAArrrrggggvvvv to 2, _a_r_g_v[0] will be ``prog'', _a_r_g_v[1] will be ``infile'', and _a_r_g_v[2] will be NULL. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS arguments, command line, options PPPPaaaaggggeeee 7777